Skip to content

feat: add unified OTel plugin factory - #905

Merged
zhongkechen merged 6 commits into
aws:mainfrom
zhongkechen:feat/unified-otel-factory-904
Nov 6, 2026
Merged

zhongkechen merged 6 commits into
aws:mainfrom
zhongkechen:feat/unified-otel-factory-904

Conversation

@zhongkechen

@zhongkechen zhongkechen commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Issue #, if available

Closes #904.

Description of changes

Users can import create_otel_plugin_factory and register create_otel_plugin_factory() for the execution view or create_otel_plugin_factory(config, mode="invocation") for the invocation view. Each call constructs a new factory of the selected view's class, passing config through unchanged and carrying that class's exclusive_group and registration metadata; the SDK then builds a fresh plugin for each invocation. Calls are not memoized, so register exactly one: two factories of the same view in plugins are rejected at registration as a duplicate in the aws-durable-execution-otel-view exclusive group. Existing released factory APIs remain supported.

DURABLE_EXECUTION_PLUGINS=otel selects the existing default execution factory. It resolves to the same object as otel-execution, so listing both loads a single factory: the loader skips the second by identity and logs a warning. Listing otel with otel-invocation names two different views and raises PluginLoadError. The Java SDK builds a separate factory per provider and rejects otel,otel-execution outright, so a multi-alias value is not portable across SDKs; the README tells operators to set exactly one name.

The README and the existing logger example demonstrate the new API and the provider/layer prerequisites. The quick start and the index.py handler example stay on mode="invocation", which is the view this guide's trace examples and screenshots document; moving them to the no-mode default would have silently changed the documented span tree.

from aws_durable_execution_sdk_python_otel import create_otel_plugin_factory

execution = create_otel_plugin_factory()
invocation = create_otel_plugin_factory(mode="invocation")

Register one returned factory in the handler's plugins list.

Design

  • Problem: Callers must choose between two factory names, and environment loading has no short default OTel entry point.
  • Cause: The package exposes only view-specific factories and entry points.
  • Options: Merging the plugin implementations would change more code than this API needs. A forwarding factory adds lifecycle and metadata responsibilities. A static-method holder adds an otherwise unused class around a selector.
  • Chosen: A module-level create_otel_plugin_factory function in the existing factory module, constructing the selected view's factory, plus an entry-point alias. This keeps one import while reusing initialization, validation, and invocation behavior.
  • Removals: No existing released API is removed. The new public surface is one function, with three overloads — two Literal modes and a str mode for a value read from configuration at runtime — plus the otel entry point. There is no holder class or additional runtime module.
  • Root cause for a bug fix: Not applicable; this is an additive feature.

Validation and assumptions

Validated at commit 1ea4d0fc25a945b10d8ba13768edbbdac03ed44b in CI run 41887190850. All Python 3.11, 3.12, 3.13, and 3.14 build jobs passed.

The Python 3.13 job confirms:

  • OTel type checking passed for 47 source/test files, covering the literal-mode and runtime str overloads.
  • Repository tests and coverage: 6,717 tests and 24 subtests passed, 6 tests skipped.
  • Installed core/OTel wheel tests: 959 passed, including selector, alias loading, replay, concurrency, and installed entry-point coverage.
  • Installed lifecycle compatibility: 12 passed; legacy OTel registration rejection: 4 passed.
  • Built wheel hashes and installed source bytes were verified, including all 17 OTel source files.

Provider and lifecycle checks use the actual core SDK and OpenTelemetry SDK with in-memory exporters. Live Lambda/ADOT/X-Ray export remains unverified; cloud tests were skipped in this run.

Decisions not covered by the issue or the design note

  • Use a plain function rather than a static holder: it directly selects a factory and needs no instances or mutable holder attributes.
  • Explicit None for mode raises ValueError, like other unsupported values. Omission selects execution mode.
  • Configuration remains the original object, preserving the existing Python factories' behavior.
  • Accept a mode read from configuration at runtime. A plain str matched neither Literal overload even though it works, and an unsupported value still raises ValueError.
  • Keep the logger example, the quick start, and the handler example in invocation mode so adopting the unified entry point preserves their documented telemetry.

Edited test expectations

  • Entry-point tests include otel and assert identity with the existing execution factory.
  • Existing registration and replay matrices retain their original cases and assertions. Two focused public-function resume cases cover the new API without duplicating every legacy permutation.
  • The concurrency test runs both views through the new function and checks operation parenting; the existing invocation-log assertions remain unchanged.
  • Real-entry-point tests cover default execution loading, alias deduplication, conflict with an explicit invocation factory, and otel,otel-invocation in both orders.
  • test_installed_entry_points_preserve_alias_identity skips when the distribution is not installed in the environment, because the declared entry points are already covered from pyproject.toml in test_plugin_factory.py.

Checklist

  • Every new selection branch has a test that fails without it: default/explicit execution, explicit invocation, and invalid mode selection.
  • Every edited test expectation is listed above with its reason.
  • Bug-fix-first-failing-test requirement: not applicable to this feature.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Companion pull requests

These SDK changes can merge independently. Cross-language guide updates can follow the corresponding package releases.

@zhongkechen
zhongkechen deployed to ai-pr-review-runtime November 3, 2026 21:08 — with GitHub Actions Active
zhongkechen added a commit to aws/aws-durable-execution-sdk-js that referenced this pull request Nov 3, 2026
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

### Issue Link, if available

Closes #1170.
Related implementations: [Java
#872](aws/aws-durable-execution-sdk-java#872),
[Python
#904](aws/aws-durable-execution-sdk-python#904).

### Description

Users can select either OTel view through `createOtelPluginFactory()`,
with execution as the default and `{ mode: "invocation" }` selecting
invocation mode. The factory snapshots existing configuration values and
returns the original implementation's factory, preserving its
registration metadata and per-invocation lifecycle. Existing factory
exports and provider subpaths remain supported.

The package root now exports the existing lazy execution provider,
allowing `DURABLE_EXECUTION_PLUGINS=@aws/durable-execution-sdk-js-otel`
without handler-side plugin registration. The provider/exporter must
still be configured by ADOT or the application.

### Demo/Screenshots

```typescript
import { createOtelPluginFactory } from "@aws/durable-execution-sdk-js-otel";

createOtelPluginFactory();
createOtelPluginFactory({ mode: "invocation", enrichLogger: false });
```

Both results are factories for the handler's `plugins` list. The README
and new `otel/unified-factory` example demonstrate registration and
durable resume.

### Design

Design note: #1170 describes the selector design.

1. **Problem:** Selecting a view requires different imports, and
environment loading has no default package-root entry point.
2. **Cause:** The package exposes two separate factory constructors and
two provider subpaths.
3. **Options:** Replacing the old factories breaks callers; merging the
implementations adds unnecessary lifecycle and telemetry risk. A small
selector can reuse the existing factories unchanged.
4. **Chosen:** Export `createOtelPluginFactory(options?)`, following the
existing `createExecutionOtelPluginFactory` and
`createInvocationOtelPluginFactory` naming. Resolve mode once, reject
unsupported modes, and return the selected factory directly. Re-export
the existing execution provider at the root to retain lazy
initialization and metadata without another wrapper.
5. **Removals:** None. No SDK invariant or telemetry behavior changes.

Net OTel runtime source change: +36 lines. Three new named exports:
`createOtelPluginFactory`, `OtelPluginFactoryOptions`, and
`durableExecutionPluginProvider`.
Root cause for a bug fix: not applicable; this is an additive feature.

### Assumptions

- Factory registration, exclusivity, concurrent execution isolation, and
replay are exercised with the current real core SDK and local runner.
Provider behavior is tested with the actual OpenTelemetry SDK and
in-memory exporter.
- Packed ESM/CommonJS exports, package-root environment loading, both
existing subpaths, and public typings were checked using isolated
installed-package fixtures rebuilt from this checkout.
- **Unverified:** Live Lambda/ADOT deployment and Node.js 22 runtime
execution. Local validation used Node.js 24.21.0; no AWS deployments
were run.

### Decisions not covered by the issue or the design note

- The unified entry point is a plain `createOtelPluginFactory` function,
matching the existing JavaScript factory API and avoiding a public
holder object. It returns the selected factory unchanged.
- Invalid explicit modes, including `null`, throw `TypeError`;
omitted/undefined modes default to execution.
- `createOtelPluginFactory(options)` shallow-copies the configuration
when the factory is created, so later assignments to the caller's
options cannot change the selected configuration. The existing factories
keep their current behavior: they read the original configuration object
on the first invocation.
- The unified-factory example is `localOnly: true`: its test retains
workflow/history coverage, while the OTel integration test covers
telemetry in both modes. This avoids a redundant cloud deployment and
intentionally leaves the example out of `template.yml`.
- Exact-optional consumer checks use `skipLibCheck` for existing
unrelated core logger declaration errors, matching the established
installed-header fixture. A separate normal strict check validates
declarations without that skip.

### Checklist

- [x] I have filled out every section of the PR template
- [x] I have thoroughly tested this change
- [x] Every new branch has a test that fails without it
(default/execution, invocation, and invalid mode)
- [x] For a bug fix: not applicable
- [x] Every edited test expectation is listed: the new invalid-mode test
now checks `TypeError` as well as the existing error message, protecting
the documented error contract. No pre-existing test expectations were
changed.

### Testing

- Focused OTel factory unit, composed, integration, and
packaged-consumer tests: **4 files, 27 tests passed**. Global setup
rebuilt core, testing SDK, and OTel CJS/ESM/declarations first. These
cover mode selection, configuration forwarding,
registration/exclusivity, replay/concurrency, and packed ESM/CommonJS
imports and public typings for `createOtelPluginFactory`.
- `npx tsc --noEmit --project
packages/aws-durable-execution-sdk-js-otel/tsconfig.json`: passed.
- `npm run lint -- --max-diagnostics=20`: passed, 1,329 files checked.
- The unified-factory example's local test passed against the rebuilt
candidate packages, including recorded-history validation.
- The actual SAM generator was checked with the example's `localOnly`
configuration: it excludes the example from local and integration
templates; a negative control with `localOnly: false` emits the
function.

#### Unit Tests

Added default/explicit selection, configuration forwarding, factory
identity/registration metadata, invalid-mode error type and message,
mode snapshotting, and import/provider laziness checks.

#### Integration Tests

Added real-loader exclusivity checks, concurrent public handlers with
suspension/replay, and packed ESM/CommonJS/type/environment-loading
checks. No new language-neutral conformance requirement is needed
because telemetry semantics are unchanged.

#### Examples

Added `otel/unified-factory` with a durable step/wait/resume workflow
and a local-only recorded-history test. The sample is excluded from
generated SAM templates and cloud integration deployment; telemetry
assertions remain in the OTel package integration test. Updated OTel
README usage and environment-loading guidance.

### Companion SDK pull requests

- [Java](aws/aws-durable-execution-sdk-java#873)
-
[Python](aws/aws-durable-execution-sdk-python#905)

These SDK changes can merge independently. Cross-language guide updates
can follow the corresponding package releases.

---------

Co-authored-by: Silan He <16982279+SilanHe@users.noreply.github.com>
Review feedback on aws#905.

The quick start and the handler example had moved to
`create_otel_plugin_factory()`, which is Workflow-rooted, silently
changing the span tree this guide documents and illustrates. Both are
back on `mode="invocation"`, matching the logger example, with a pointer
to Trace Structure for the execution shape.

Correct "returns the existing factory directly": every call constructs a
new factory, so two of them in `plugins` are rejected as a duplicate in
the `durable-otel-view` group. State what `otel,otel-execution` actually
does -- one factory, the second skipped by identity, a warning logged --
and that Java rejects the same pair, so a multi-alias value is not
portable across SDKs.

Accept a `mode` read from configuration at runtime, which is a plain
`str` and matched neither literal overload. Skip the installed
entry-point test when the distribution is absent, since the declared
entry points are already covered from pyproject.toml, and cover
`otel,otel-invocation` in both orders to pin the matrix the Java suite
pins.
Review feedback on aws#905.

`test_factory_preserves_configuration_and_registration` compared
`factory.exclusive_group` to `expected.exclusive_group`, where `factory`
is an instance of `expected`. That is the same attribute on both sides,
so it held for any value and the assertion verified nothing.

This is what let `durable-otel-view` -- the Java SDK's group name -- sit
in the README and the docstring until `e4a5614a`: the test looked like
it pinned the value. Assert the literal
`aws-durable-execution-otel-view` instead, matching how the Java suite
pins its own group name.
Comment on lines +103 to +107
Listing `otel` with `otel-invocation` names two different views and raises
`PluginLoadError`. The Java and JS/TypeScript SDKs enforce the same one-view
contract but report a redundant second alias in their own idiom — Java rejects
`otel,otel-execution` outright — so do not rely on a multi-alias value behaving
identically across languages.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: can drop the same sentence here as well: "The Java and JS/TypeScript SDKs enforce the same one-view
contract but report a redundant second alias in their own idiom — Java rejects
otel,otel-execution outright — so do not rely on a multi-alias value behaving
identically across languages."

🤖 AI-assisted comment

Comment on lines +70 to +75
Each call constructs a new `ExecutionOtelPluginFactory` or
`InvocationOtelPluginFactory` of the selected view, carrying that class's
`exclusive_group`. Calls are not memoized, so register exactly one: two
factories of the same view in `plugins` are rejected at registration as a
duplicate in the `aws-durable-execution-otel-view` exclusive group. Both existing factory
classes remain supported, with unchanged configuration and behavior.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One failure mode isn't documented or tested: plugins=[create_otel_plugin_factory()] combined with DURABLE_EXECUTION_PLUGINS=otel raises PluginLoadError ("registered more than once in exclusive group"). The identity skip in plugin_discovery.py:504 doesn't apply because each call returns a new instance rather than the EXECUTION_OTEL_PLUGIN_FACTORY singleton, so the same-type check at :367 rejects it. The loader's docstring presents "same object passed explicitly and named in the env" as supported, which the selector can't satisfy. Suggest a README sentence (point mixed users at EXECUTION_OTEL_PLUGIN_FACTORY) plus an e2e test.

🤖 AI-assisted comment

Comment on lines +96 to +112
def test_installed_entry_points_preserve_alias_identity() -> None:
installed = {
entry.name: entry.load()
for entry in entry_points(group="aws_durable_execution.plugins")
if entry.name in {"otel", "otel-execution", "otel-invocation"}
}
if not installed:
pytest.skip(
"aws-durable-execution-sdk-python-otel is not installed in this "
"environment; test_plugin_factory.py covers the declared entry "
"points from pyproject.toml"
)
assert installed == {
"otel": EXECUTION_OTEL_PLUGIN_FACTORY,
"otel-execution": EXECUTION_OTEL_PLUGIN_FACTORY,
"otel-invocation": INVOCATION_OTEL_PLUGIN_FACTORY,
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: This repeats test_plugin_factory.py:161-168, which already checks the otel entry point against pyproject.toml. The pytest.skip also doesn't buy much: test_view_registration.py:425 and :443 need the same installed entry points and don't skip. Suggest deleting this test.

🤖 AI-assisted comment

Comment on lines +610 to +615
Calls are not memoized —
`create_otel_plugin_factory() is create_otel_plugin_factory()` is `False` — so
register exactly one. Two factories of the same view in `plugins` raise
`PluginLoadError` as a duplicate in the `aws-durable-execution-otel-view` exclusive group. A
`mode` read from configuration at runtime is accepted and type-checks as the
union of both return types.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "Calls are not memoized, register exactly one" appears here, in the setup section (:72), and in the function docstring. The new README section is ~70 lines for a small selector. Maybe in a future PR, we can try to be more concise in our README

🤖 AI-assisted comment

return ExecutionOtelPluginFactory(config)
if mode == "invocation":
return InvocationOtelPluginFactory(config)
raise ValueError("mode must be 'execution' or 'invocation'")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: now that a runtime str is accepted, it would help to show the rejected value, e.g. raise ValueError(f"mode must be 'execution' or 'invocation', got {mode!r}").

🤖 AI-assisted comment

@@ -0,0 +1,112 @@
"""Public factory selection, typing, and installed entry-point coverage."""

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: there's no otel_plugin.py module, so this file doesn't mirror one. CONTRIBUTING asks for one test file per module; consider folding these tests into tests/test_plugin_factory.py.

🤖 AI-assisted comment

assert len(invocations) == 2
operation = next(span for span in spans if span.name == "work")
expected_parents = workflows if mode == "execution" else invocations
assert any(operation.parent == parent.context for parent in expected_parents)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: any(operation.parent == ...) is weak in invocation mode. Asserting the parent is specifically the first Invocation span would make this check meaningful.

🤖 AI-assisted comment

@zhongkechen

Copy link
Copy Markdown
Contributor Author

@SilanHe Thank you for your comments. Replied to one of them. And the remaining gaps exist in tests and docs. I will follow up with a new PR.

@zhongkechen
zhongkechen merged commit 0f59815 into aws:main Nov 6, 2026
49 of 61 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add a unified OtelPlugin factory with execution defaults

2 participants